package miggy.api.memory;

import miggy.api.config.MachineDefinition;
import miggy.api.config.ConfigurationException;
import miggy.api.cpu.Size;

/*
//  Miggy - Java Amiga MachineCore
//  Copyright (c) 2008, Tony Headford
//  All rights reserved.
//
//  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
//  following conditions are met:
//
//    o  Redistributions of source code must retain the above copyright notice, this list of conditions and the
//       following disclaimer.
//    o  Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
//       following disclaimer in the documentation and/or other materials provided with the distribution.
//    o  Neither the name of the Miggy Project nor the names of its contributors may be used to endorse or promote
//       products derived from this software without specific prior written permission.
//
//  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
//  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
//  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
//  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
//  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
//  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
//  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// $Revision: 21 $
*/
/**
 * AddressSpace is an interface to the system memory and provides methods to read and write
 * byte, word and longword values.
 */
public interface AddressSpace
{
	/**
	 * Initialise the controller
	 * @param config Configuration object containing machine settings
	 * @throws ConfigurationException if Configuration holds invalid information for this component
	 */
	void init(MachineDefinition config) throws ConfigurationException;
	
	/**
	 * Reset the memory to it's power-on state
	 */
	void reset();

	/**
	 * Read a byte (8-bit) value from the specified address
	 * @param address A 24-bit memory address
	 * @return byte value read from the address
	 */
//	byte peekByte(int address);

	/**
	 * Read a word (16-bit) value from the specified address
	 * @param address A 24-bit memory address
	 * @return short value read from the address
	 */
//	short peekWord(int address);

	/**
	 * Read a longword (32-bit) value from the specified address
	 * @param address  A 24-bit memory address
	 * @return int value read from the address
	 */
//	int peekLong(int address);

	/**
	 * Write a byte (8-bit) value to the specified address
	 * @param address A 24-bit memory address
	 * @param value  The byte value to write to the address
	 */
//	void pokeByte(int address, byte value);

	/**
	 * Write a word (16-bit) value to the specified address
	 * @param address A 24-bit memory address
	 * @param value  The short value to write to the address
	 */
//	void pokeWord(int address, short value);

	/**
	 * Write a longword (32-bit) value to the specified address
	 * @param address A 24-bit memory address
	 * @param value  The int value to write to the address
	 */
//	void pokeLong(int address, int value);

	/**
	 * Read a value from the specified address. The size of the data read is specified with the
	 * size parameter.
	 * @param address  A 24-bit memory address
	 * @param size  DataSize value representing the size of the read.
	 * @return  The value read from the address
	 */
	int peek(int address, Size size);

	/**
	 * Write a value into the specified address.  The size of the write is specified with the size
	 * parameter.
	 * @param address  A 24-bit memory address
	 * @param value  The value to be written. Value will be truncated to the specified size.
	 * @param size  DataSize value representing the size of the read.
	 */
	void poke(int address, int value, Size size);


	/**
	 * Read a value from the specified address without causing any side effects
	 * such as may happen when reading from custom chip registers. Used by the debugger.
	 * The size of the data read is specified with the size parameter.
	 * @param address  A 24-bit memory address
	 * @param size  DataSize value representing the size of the read.
	 * @return  The value read from the address
	 */
	int directPeek(int address, Size size);

	/**
	 * Write a value into the specified address without causing any side effects
	 * such as may happen when reading from custom chip registers. Used by the debugger.
	 * The size of the write is specified with the size parameter.
	 * @param address  A 24-bit memory address
	 * @param value  The value to be written. Value will be truncated to the specified size.
	 * @param size  DataSize value representing the size of the read.
	 */
	void directPoke(int address, int value, Size size);


	/**
	 * Read a byte (8-bit) value from the specified address without causing any side effects
	 * such as may happen when reading from custom chip registers. Used by the debugger.
	 * @param address A 24-bit memory address
	 * @return byte value read from the address
	 */
//	byte debugPeekByte(int address);

	/**
	 * Read a word (16-bit) value from the specified address without causing any side effects
	 * such as may happen when reading from custom chip registers. Used by the debugger.
	 * @param address A 24-bit memory address
	 * @return short value read from the address
	 */
//	short debugPeekWord(int address);

	/**
	 * Read a longword (32-bit) value from the specified address without causing any side effects
	 * such as may happen when reading from custom chip registers. Used by the debugger.
	 * @param address A 24-bit memory address
	 * @return int value read from the address
	 */
//	int debugPeekLong(int address);

	/**
	 * Write a byte (8-bit) value to the specified address without causing any side effects
	 * such as may happen when writing to custom chip registers. Used by the debugger.
	 * @param address A 24-bit memory address
	 * @param value  The byte value to write to the address
	 */
//	void debugPokeByte(int address, byte value);

	/**
	 * Write a word (16-bit) value to the specified address without causing any side effects
	 * such as may happen when writing to custom chip registers. Used by the debugger.
	 * @param address A 24-bit memory address
	 * @param value  The short value to write to the address
	 */
//	void debugPokeWord(int address, short value);

	/**
	 * Write a longword (32-bit) value to the specified address without causing any side effects
	 * such as may happen when writing to custom chip registers. Used by the debugger.
	 * @param address A 24-bit memory address
	 * @param value  The int value to write to the address
	 */
//	void debugPokeLong(int address, int value);
}
